The CIHTTP Control Reference
 The Crescent Internet ToolPak HTTP Control Reference
Related Topics

Control File

CIHTTP.OCX

Object Type

CIHTTP

Purpose

The Crescent Internet HTTP control (CIHTTP) enables you to write customized World Wide Web (WWW) client applications. You can use CIHTTP to retrieve text or binary data from a Web site, to retrieve data about a page at the Web site (such as date last updated), or to post text to a Web site from within an OLE container. CIHTTP also has the ability to parse the retrieved data. The control is intended to enhance not replace a Web browser's functionality.

Some typical applications that you might build with this control include:

Web Data Retrieval Applications

Use the CIHTTP control to access data from a Web site and place it in a spreadsheet or other customized database. For example, you might create an application that pulls stock data from the Internet and places it in an Excel spreadsheet.

Web Data Entry Applications

Create applications in which users enter data to a form, then use the CIHTTP control to post the data form to a Web site.

Web Crawler Applications

Create a Web Crawler that searches the Internet for Web sites that contain information relevant to specific keywords.

Comments

If you are creating a control array of CIHTTP controls at run time, you must set each control's Visible property to True, before you attempt to establish an connection. Otherwise, the CIHTTP control fires a WSAError event that returns an error_number of 22. The following example creates a second CIHTTP control and sets its Visible property to True.

Load CIHTTP(1)
CIHTTP(1).Visible = True

Properties

About	AnchorListBoxName c	Container
EventState c	ExpandLinks c	Height
HostAddress c	HostName c	HTMLPageTextWithoutTags c
HTMLPageTextWithTags c	HTTPHeader c	HTTPPort c
ImageFileListBoxName c	Index	Left
LocalFileName c	MethodState c	Name
Object	Parent	ParseIncomingData c
ParseURL c	Password c	ProxyServerAddress c
ProxyServerName c	RemotePath c	Tag
TagListBoxName c	Top	URL c
User c	Visible	WhatsThisHelpID
Width	WWWSiteName c	ZOrder
Events

DragDrop	DragOver	EventStateChanged c
ExternalProtocol c	FileClosed c	HTTPServerConnectionClosed c
HTTPServerConnection c	ListBoxesPopulated c	MethodStateChanged c
PacketReceived c	PacketSent c	SocketClosed c
TotalFileBytesReceived c	WSAError c
Methods

CleanupConnection c	ConnectToHTTPServer c	Drag
DragIcon	DragMode	GET c
HEAD c	Move	POST c
SendHTTPCommand c	ShowWhatsThis
c A custom or modified property, method, or event.


AnchorListBoxName Property

Applies To

CIHTTP

Purpose

The AnchorListBoxName property sets the name of a ListBox object that is bound to the CIHTTP control. When the control retrieves an HTML page from a Web site, the anchor ListBox is populated with a list of the anchors from the parsed HTML page, if the ParseIncomingData property is set to True.

 Syntax

Set [Form.]CIHTTP.AnchorListBoxName = ObjectName

Data Type

Object

Usage

Read/Write at run time. Unavailable at design time.

Comments

The ParseIncomingData property must be set to True before, the AnchorListBoxName property can populate a ListBox with anchors.

An anchor is a hypertext link. The link can be to another location within the document, to another document on the same Web server, or to a document on another Web server. The anchor ListBox object displays the anchors in a given Web page. You can write additional code that lets you use the anchors to jump to those sites.

NOTE  	Links to locations within the same document and links to other documents on the same server might be relative and not fully qualified URLs. However, if you set the ExpandLinks property to True, all links returned in the anchor ListBox will be fully qualified URLs.

If the data retrieved is a binary file (.exe or image file), CIHTTP ignores this property.

When the anchor ListBox, image file ListBox, and tag ListBox are populated, the ListBoxesPopulated event fires.

See Also

ImageFileListBoxName, ListBoxesPopulated, ParseIncomingData, TagListBoxName


EventState Property

Applies To

CIHTTP

Purpose

The EventState Property returns the event currently in progress.

Syntax

[Integer] = [Form.]CIHTTP.EventState

Data Type

Integer

Usage

Read-only at run time. Unavailable at design time.

Comments

CIHTTP updates EventState when an event fires. When the EventState Property changes, CIHTTP fires the EventStateChanged event. The valid EventState Property values are listed in the following table:

This event. . .	has this constant. . .	with this integer value. . .
ListBoxesPopulated	CIHTTP_LBPOP	120
HTTPServerConnection	CIHTTP_CONN	121
SocketClosed	CIHTTP_SCLOSED	122
HTTPServerConnectionClosed	CIHTTP_CONNCLOSED	123
FileClosed	CIHTTP_FCLOSED	124
You can test the EventState to initiate an action or control program flow.

See Also

EventStateChanged


ExpandLinks Property

Applies To

CIHTTP

Purpose

The ExpandLinks property enables the expansion of the relative path of HTML documents, anchors, or image links into full URLs.

Syntax

[Form.]CIHTTP.EpandLinks[ = Boolean]

Data Type

Boolean

Usage

Read/Write at design time and run time.

Comments

Setting the ExpandLinks property to True causes the CIHTTP control to expand a relative path ("/somedir/somedoc.htm") into a fully qualified URL ("http://somehost/somedir/somedoc.htm") for HTML pages, anchors, and image files that appear in list boxes specified by the AnchorListBoxName and ImageFileListBoxName properties. The ExpandLinks property is usually set at design time.

By setting the ExpandLinks property to True, you can ensure that all links parsed by the CIHTTP control become fully qualified URLs. Having fully qualified URLs makes it easy to navigate other links.

The default value is False, which disables the expansion of the relative path. False is used for backward compatibility with previous versions of CIHTTP. However, in most cases, you should enable the ExpandsLinks property by setting it to True.

See Also

AnchorListBoxName, ImageFileListBoxName


HostAddress Property

Applies To

CIHTTP

Purpose

The HostAddress property sets or returns the IP address of the Web server.

Syntax

[Form.]CIHTTP.HostAddress[ = String]

Data Type

String

Usage

Read/Write at design time.

Comments

The HostAddress identifies the host to the network (the Internet). HostAddress consists of the network number and the local host. An example of an IP address is:

198.137.64.1

To connect to a Web server you must provide either the HostName or the HostAddress property. If you provide both, CIHTTP uses the HostName. In addition, if you are connected to the Internet via a Proxy server (known as a firewall system), you must also provide the ProxyServerAddress or ProxyServerName. If you provide both, CIHTTP uses the ProxyServerName.

See Also

ConnectToHTTPServer, HostName, ProxyServerAddress, ProxyServerName


HostName Property

Applies To

CIHTTP

Purpose

The HostName property sets the name of the Web server.

Syntax

[Form.]CIHTTP.HostName[ = String]

Data Type

String

Usage

Read/Write at design time and run time.

Comments

The HostName is the name that identifies an HTTP server to the Internet. Depending on your connection to the Internet, the HostName might contain simply a machine name like crescentserver, or it can be a fully qualified Internet name that follows this format: machine.organizationname.com. Contact your site administrator to determine the correct format to supply.

Set HostAddress or HostName before calling the ConnectToHTTPServer method. If you provide both, CIHTTP uses the HostName. In addition, if you are connected to the Internet via a Proxy server (known as a firewall system), you must also provide the ProxyServerAddress or ProxyServerName. If you provide both, CIHTTP uses the ProxyServerName.

See Also

ConnectToHTTPServer, HostAddress, ProxyServerAddress, ProxyServerName


HTMLPageTextWithoutTags Property

Applies To

CIHTTP

Purpose

The HTMLPageTextWithoutTags property returns the parsed Web page without HTML formatting tags.

Syntax

String = [Form.]CIHTTP.HTMLPageTextWithoutTags

Data Type

String

Usage

Read-only at run time. Unavailable at design time.

Comments

Use the contents of the HTMLPageWithTags property to display the HTML page excluding the HTML formatting tags.

See Also

HTMLPageTextWithTags


HTMLPageTextWithTags Property

Applies To

CIHTTP

Purpose

The HTMLPageTextWithTags property returns the parsed Web page with HTML formatting tags.

Syntax

String = [Form.]CIHTTP.HTMLPageTextWithTags

Data Type

String

Usage

Read-only at run time. Unavailable at design time.

Comments

Use the contents of the HTMLPageWithTags property to display the HTML page including the tags. You must also set the ParseIncomingData property to true.

See Also

HTMLPageTextWithoutTags, ParseIncomingData


HTTPHeader Property

Applies To

CIHTTP

Purpose

The HTTPHeader property lets you add additional information to a request that you send to an HTTP server and stores the header information the HTTP server returns.

Syntax

[Form.]CIHTTP.HTTPHeader[ = String]

Data Type

String

Usage

Read/write at run time. Unavailable at design time.

Comments

The default value for the HTTPHeader property is an empty string, which sends a header requesting that information be sent back in a format that HTTP/1.0 supports.

You can use the HTTPHeader property when sending a request to or parsing the header returned from an HTTP server. For example:

Before you call a GET, POST, or HEAD method you can add additional fields to the HTTPHeader property.

When the FileClosed event fires after the GET, POST, or HEAD method completes, you can parse the header returned from the HTTP server in the HTTPHeader property.

See Also

FileClosed, GET, HEAD, ParseURL, POST


HTTPPort Property

Applies To

CIHTTP

Purpose

The HTTPPort property sets the number of the port used for HTTP communications.

Syntax

[Form.]CIHTTP.HTTPPort[ = Integer]

Data Type

Integer

Usage

Read/Write at design time and run time.

Comments

The default is 80.


ImageFileListBoxName Property

Applies To

CIHTTP

Purpose

The ImageFileListBoxName property sets the name of a ListBox control that is bound to the CIHTTP control. When the control retrieves an HTML page from a Web site, the image file ListBox is populated with a list of image files from the parsed HTML page, if the ParseIncomingData property is set to True.

Syntax

Set [Form.]CIHTTP.ImageFileListBoxName = ObjectName

Data Type

Object

Usage

Read/Write at run time. Unavailable at design time.

Comments

The ParseIncomingData property must be set to True, before the ImageFileListBoxName property can populate a ListBox with image files.

CIHTTP ignores this property if the data retrieved is not an HTML page.

When the anchor ListBox, image file ListBox, and the tag ListBox are populated, the ListBoxesPopulated event fires.

NOTE  	Links to locations within the same document and links to other image files on the same server might be relative and not fully qualified URLs. However, if you set the ExpandLinks property to True, all links returned in the image file ListBox will be fully qualified URLs.

See Also

AnchorListBoxName, ListBoxesPopulated, ParseIncomingData, TagListBoxName


LocalFileName Property

Applies To

CIHTTP

Purpose

The LocalFileName property sets a path and filename on the local machine.

Syntax

[Form.]CIHTTP.LocalFileName[ = String]

Data Type

String

Usage

Read/Write at design time and run time.

Comments

Use the local file to store data retrieved from the Web via the GET method.


MethodState Property

Applies To

CIHTTP

Purpose

The MethodState Property returns the method currently in progress.

Syntax

[Integer] = [Form.]CIHTTP.MethodState

Data Type

Integer

Usage

Read-only at run time. Unavailable at design time.

Comments

CIHTTP updates MethodState when you call a method like GET, HEAD, or POST. When the MethodState Property changes, CIHTTP fires the MethodStateChanged event. The valid MethodState Property values are listed in the following table:

This method...	has this constant...	with this integer value...
GET	CIHTTP_GET	14
HEAD	CIHTTP_HEAD	15
POST	CIHTTP_POST	16
You can test the MethodState to initiate an action or control program flow.

See Also

MethodStateChanged


ParseIncomingData Property

Applies To

CIHTTP

Purpose

The ParseIncomingData property sets whether or not to parse the data retrieved from a Web site.

Syntax

[Form.]CIHTTP.ParseIncomingData[ = Boolean]

Data Type

Boolean Integer

Usage

Read/Write at design time and run time.

Comments

If the data is a file, this property is ignored.

Value	Behavior
True	CIHTTP parses the data based on the HTML tags.
False	CIHTTP does not parse the data; it assumes the data is binary.


ParseURL Property

Applies To

CIHTTP

Purpose

The ParseURL property automatically validates the URL specified in the URL property whenever it is set, and sets the values of the following properties: HostName, HTTPHeader, HTTPPort, Password, RemotePath, and User. If the URL is incomplete, an attempt is made to build a complete HTTP URL.

Syntax

[Form.]CIHTTP.ParseURL[ = Boolean]

Data Type

Boolean

Usage

Read/Write at design time and run time.

Comments

Setting the ParseURL property to True causes the following to happen when the URL property is set:

If the URL is complete, but it is not an HTTP URL, such as an FTP site ("ftp://somerserver"), then the CIHTTP control fires the ExternalProtocol event with the URL as the parameter. No parsing is performed.

If the URL is incomplete ("www.crescent.com"), then the CIHTTP control assumes that an HTTP URL was intended. It attempts to build a complete HTTP URL using the information in the URL and using default values as well as previous values for the properties making up the URL.

If the URL specified in the URL property is a complete HTTP URL ("http://crescent.progress.com"), the CIHTTP control parses the URL and sets the following properties: HostName, HTTPHeader, HTTPPort, Password, RemotePath, and User, according to the rules specified in the following table.

This property is set....	When this condition exists...
HostName	The host name must be present for an HTTP URL to be valid.  If the host name is an IP address (four integers separated by periods), then it is placed in the HostAddress property and the HostName property is set to an empty string. Otherwise, the host name is placed in the HostName property and the HostAddress property is set to an empty string.
HTTPHeader	If any information is present after the document path (starting with "HTTP//"), it is placed in the HTTPHeader property and removed from the string assigned to the URL property. The HTTPHeader property is provided for backward compatibility with previous versions of CIHTTP.
HTTPPort	A proxy server if already specified in the ProxyServerName and the ProxyServerAddress properties, overrides the HTTP port in the URL. If a proxy server is not set (both the ProxyServerName and ProxyServerAddress properties are empty strings) then the HTTP port, if present, is placed in the HTTPPort property. If no HTTP port is specified in the URL, then the HTTPPort property is set to 80, which is the default value.
Password	When the password is present, it is placed in the Password property; otherwise, the Password property is set to an empty string for security purposes.  The password is removed from the string that is assigned to the URL property.
RemotePath	If a remote path is present, it is placed in the RemotePath property; otherwise, the RemotePath property is set to the root directory ( "/").
User	When the user name is present, it is placed in the User property; otherwise, the User property is set to an empty string for security purposes.  The user name is removed from the string that is assigned to the URL property.
After the URL property has been parsed, you might want to check the values of the following properties in order to update text boxes or other controls that display URL information to users.

HostAddress	HostName	HTTPHeader	HTTPPort
Password	RemotePath	URL	User
NOTE  	The default value of False is provided for backward compatibility with previous versions of CIHTTP. It disables parsing of the HTTP URL.

SeeAlso

HostAddress, HostName, HTTPHeader, HTTPPort, Password, RemotePath, URL, User


Password Property

Applies To

CIHTTP

Purpose

The Password property sets the password used to access an HTTP host.

Syntax

[Form.]CIHTTP.Password[ = String]

Data Type

String

Usage

Read/Write at design time and run time.

Comments

The Password property and the User property when used together, support the Basic Authorization for an HTTP server. The default value is an empty string.

The Password property, if it is not an empty string, is sent to an HTTP server along with the User property, when a call is made to the GET, HEAD, or POST methods.

The Password property can be set directly or automatically from a valid HTTP URL when the ParseURL property is set to True.

See Also

ParseURL, User


ProxyServerAddress Property

Applies To

CIHTTP

Purpose

The ProxyServerAddress sets the IP address of the proxy server (the server that acts as the firewall).

Syntax

[Form.]CIHTTP.ProxyServerAddress[ = String]

Data Type

String

Usage

Read/Write at design time.

Comments

The ProxyServerAddress identifies the proxy server to the Internet. The ProxyServerAddress, like the HostAddress, consists of the network number and the local host number. When your site uses a firewall system, you must provide either the ProxyServerAddress or the ProxyServerName as well as the HostName or HostAddress to retrieve objects/documents from a Web server.

An example of an IP address is:

198.137.64.1

NOTE  	If you provide both a HostName and HostAddress, CIHTTP uses the HostName. If you provide both a ProxyServerName and a ProxyServerAddress, CIHTTP uses the ProxyServerName.

See Also

ConnectToHTTPServer, HostAddress, HostName, ProxyServerName


ProxyServerName Property

Applies To

CIHTTP

Purpose

The ProxyServerName property sets the name of the proxy server (the server that acts as the firewall).

Syntax

[Form.]CIHTTP.ProxyServerName[ = String]

Data Type

String

Usage

Read/Write at design time and run time.

Comments

The ProxyServerAddress identifies the proxy server to the Internet. When you are connected to the Internet via a Proxy server (known as a firewall system), you must provide the ProxyServerAddress or ProxyServerName. As with HostName and HostAddress, if you provide both, CIHTTP uses the ProxyServerName.

See Also

ConnectToHTTPServer, HostAddress, ProxyServerAddress


RemotePath Property

Applies To

CIHTTP

Purpose

The RemotePath property contains the path and file name of the file to be retrieved from the HTTP server.

Syntax

[Form.]CIHTTP.RemotePath[ = String]

Data Type

String

Usage

Read-only at run time. Unavailable at design time.

Comments

Usually you do not set the RemotePath property directly. It is automatically set from the URL property, when the URL is a valid HTTP URL and the ParseURL property is set to True.

The default value for the RemotePath property is an empty string. When the URL property is parsed, if it does not contain a remote path, by default, the remote path becomes the root directory ( "\" ).

See Also

ParseURL


TagListBoxName Property

Applies To

CIHTTP

Purpose

The TagListBoxName property sets the name of a ListBox control that is bound to the CIHTTP control. When the control retrieves an HTML page from a Web site, the tag ListBox is populated with a list of the tags from the parsed HTML page, if the ParseIncomingData property is set to True.

Syntax

Set [Form.]CIHTTP.TagListBoxName = ObjectName

Data Type

Object

Usage

Read/Write at run time. Unavailable at design time.

Comments

The ParseIncomingData property must be set to True before, the TagListBoxName property can populate a ListBox with tags.

A tag is a code for a format to be applied to the Web page, for example <title>. The tag ListBox object displays the tags in a given Web page so you can view the styles in the document. This information can be useful when searching for uses of specific tags.

When the anchor ListBox, image ListBox, and tag ListBox are populated, the ListBoxesPopulated event fires.

If the data retrieved is a binary file (.exe or image file), CIHTTP ignores this property.

See Also

AnchorListBoxName, ImageFileListBoxName, ListBoxesPopulated, ParseIncomingData


URL Property

Applies To

CIHTTP

Purpose

The URL property sets the Uniform Resource Locator of the current request.

Syntax

[Form.]CIHTTP.URL[ = String]

Data Type

String

Usage

Read/Write at design time and run time.

Comments

A Uniform Resource Locator identifies the location of an object on the Internet using a standard address syntax. It contains information in the address that indicates how you might access the object. The following example illustrates the URL for the Progress Software Web page:

URL	http://www.progress.com


User Property

Applies To

CIHTTP

Purpose

The User property sets the name of the user for accessing hosts that require user authentication.

Syntax

[Form.]CIHTTP.User[ = String]

Data Type

String

Usage

Read/Write at design time and run time.

Comments

The User property and the Password property when used together, support the Basic Authorization for an HTTP server. The default value is an empty string.

The User property, if it is not an empty string, is sent to HTTP server along with the Password property, when a call is made to the GET, HEAD, or POST methods.

The User property can be set directly or automatically from a valid HTTP URL when the ParseURL property is set to True.

See Also

Password, ParseURL


WWWSiteName Property

Applies To

CIHTTP

Purpose

The WWWSiteName property contains the name of the current Web page. It is extracted from the <title> tag of the retrieved HTML page if one exists.

Syntax

String = [Form.]CIHTTP.WWWSiteName

Data Type

String

Usage

Read only at run time. Unavailable at design time.

See Also

TagListBoxName


EventStateChanged Event

Applies To

CIHTTP

Purpose

The EventStateChanged event fires when the value of the EventState property changes.

Syntax

Sub CIHTTP_EventStateChanged(ByVal state As Integer)

Comments

The EventState property records the state of CIHTTP; its value changes in response to other CIHTTP events. You can test the EventState property to determine a state change and thus initiate an action, or control program flow. The valid EventState property values are listed in the following table:

This event. . .	has this constant. . .	with this integer value. . .
ListBoxesPopulated	CIHTTP_LBPOP	120
HTTPServerConnection	CIHTTP_CONN	121
SocketClosed	CIHTTP_SCLOSED	122
HTTPServerConnectionClosed	CIHTTP_CONNCLOSED	123
FileClosed	CIHTTP_FCLOSED	124
See Also

EventState


ExternalProtocol Event

Applies To

CIHTTP

Purpose

The ExternalProtocol event fires when the string assigned to the URL property is a valid URL, but not an HTTP URL and if the ParseURL property is set to True.

Syntax

Sub CIHTTP_ExternalProtocol(ByVal UnsupportedURL As String)

Comments

When a URL is complete, but it is not an HTTP URL, the URL is passed as an UnsupportedURL parameter to the ExternalProtocol event by the URL property. The following table lists examples of URLs that will and will not fire the ExternalProtocol event.

This URL...	Fires the ExternalProtocol Event...
http://www.somehost.com/	No (A valid HTTP URL)
junk_string_not_a_url	No (Not a valid URL)
ftp://ftp.somehost.com/	Yes (A valid URL, but not a valid HTTP URL)
gopher://gopher.somehost.com/	Yes (A valid URL, but not a valid HTTP URL)
If you do not want to support non-HTTP URLs, you can write code in this event to cleanup and cancel pending connections. You can also pass the URL to another routine in your application or to another program that can handle this type of URL. For example:

Private Sub CIHTTP1_ExternalProtocol(ByVal UnsupportedURL As String)

If CIHTTP1.ProxyServerName = "" And CIHTTP1.ProxyServerAddress = "" Then
' Insert code here to alert the user that URL is unsupported, because 'a proxy server is not being used
End If
' Otherwise, continue and assume the proxy server handles this URL
End Sub

NOTE  	If you are connecting through a proxy server, you can ignore this event.

See Also

ParseURL


FileClosed Event

Applies To

CIHTTP

Purpose

The FileClosed event fires when the file stream (specified by the LocalFileName property) on the client closes.

Syntax

Sub CIHTTP_FileClosed()

Comments

The FileClosed event indicates that communications with the Web server has terminated, and that all data has been retrieved and parsed.

See Also

LocalFileName


HTTPServerConnection Event

Applies To

CIHTTP

Purpose

The HTTPServerConnection event fires when CIHTTP establishes a connection to a Web server.

Syntax

Sub CIHTTP_HTTPServerConnection()

Comments

Once the HTTPServerConnection event fires, your application can start to interact with the Web server by invoking the GET, POST, or the SendHTTPCommand methods.

Because the HTTPServerConnection event fires when a connection is established, the HTTPServerConnection_Event module is a good module to place any initial code.

See Also

GET, HTTPServerConnectionClosed, POST, SendHTTPCommand


HTTPServerConnectionClosed Event

Applies To

CIHTTP

Purpose

The HTTPServerConnectionClosed event fires when a connection to a Web server terminates.

Syntax

Sub CIHTTP_HTTPServerConnectionClosed()

Comments

Connections are terminated at the request of the Web server.

See Also

HTTPServerConnection


ListBoxesPopulated Event

Applies To

CIHTTP

Purpose

The ListBoxesPopulated event fires when the AnchorListBox, ImageListBox, and TagListBox objects have been filled.

Syntax

Sub CIHTTP_ListBoxesPopulated()

Comments

The event fires once after all of the ListBoxes are populated.

See Also

AnchorListBoxName, ImageFileListBoxName, ListBoxesPopulated, TagListBoxName


MethodStateChanged Event

Applies To

CIHTTP

Purpose

The MethodStateChanged event fires when the value of the MethodState Property changes.

Syntax

Sub CIHTTP_MethodStateChanged(ByVal state As Integer)

Comments

The MethodState Property records the state of CIHTTP; its value changes in response to other CIHTTP events. You can test the MethodState Property to determine a state change and thus initiate an action, or control program flow. The valid MethodState Property values are listed in the following table:

This method...	has this constant...	with this integer value...
GET	CIHTTP_GET	14
HEAD	CIHTTP_HEAD	15
POST	CIHTTP_POST	16
See Also

MethodState


PacketReceived Event

Applies To

CIHTTP

Purpose

The PacketReceived event fires when CIHTTP receives a packet from the connected Web server.

Syntax

Sub CIHTTP_PacketReceived(ByVal Packet As String, ByVal bytes_in As Integer)

Comments

The bytes_in value is the number of bytes in the current packet.

The Packet contains data received from the server; it can contain a Web page or header information from a Web page depending on the method used to obtain the packet. The bytes_in value is the number of bytes in the current packet.

See Also

PacketSent, GET, HEAD, SendHTTPCommand, Total File Bytes Received


PacketSent Event

Applies To

CIHTTP

Purpose

The PacketSent event fires when CIHTTP sends a packet to a Web server.

Syntax

Sub CIHTTP_PacketSent(ByVal bytes_out As Integer)

Comments

The value of bytes_out is the number of bytes in the current packet. Packets are sent in response to the all of the methods except: CleanupConnection.

See Also

GET, HEAD, PacketReceived, POST, SendHTTPCommand


SocketClosed Event

Applies To

CIHTTP

Purpose

The SocketClosed event fires when the socket closes.

Syntax

Sub CIHTTP_SocketClosed()

Comments

The socket should remain open during program execution. If the SocketClosed event fires while your application is running, an error condition has occurred.

See Also

CleanupConnection


TotalFileBytesReceived Event

Applies To

CIHTTP

Purpose

The TotalFileBytesReceived event fires repeatedly as packets are received from the server.

Syntax

Sub CIHTTP_TotalFileBytesReceived(ByVal bytes_in As Long)

Comments

The bytes_in value is the total number of bytes received during the file transfer. It increments each time a packet is received. Use bytes_in as the byte counter for the file transfer.

See Also

PacketReceived


WSAError Event

Applies To

CIHTTP

Purpose

The WSAError event fires when CIHTTP receives a WinSock error.

Syntax

Sub CIHTTP_WSAError(ByVal error_number As Integer)

Comments

Use the WSAError event to monitor the WinSock activity. The error_number identifies the WinSock error that occurred.


CleanupConnection Method

Applies To

CIHTTP

Purpose

The CleanupConnection method closes the socket and cleans up WinSock.

Syntax

CIHTTP.CleanupConnection

Data Type

None

Comments

By default CIHTTP opens the socket when you invoke the ConnectToHTTPServer method and closes it when the Web server notifies the client that the transaction is finished. A transaction can be finished when the server's got your data from the POST method, or it's sent all of the data in response to the GET or HEAD methods.

Use CleanupConnection to clear errors that might occur when a method fails, or in other cases where the socket does not close properly and you need to restart the connection process. CleanupConnection fires the SocketClosed event.

NOTE  	Use this method only when all else fails.

See Also

ConnectToHTTPServer, SocketClosed, WSAError


ConnectToHTTPServer Method

Applies To

CIHTTP

Purpose

The ConnectToHTTPServer method establishes a connection to a Web server.

Syntax

nResult = CIHTTP.ConnectToHTTPServer

Data Type

Integer

Comments

You must establish a connection to the Web server before CIHTTP can perform any send or retrieve functions. To establish a connection, you must provide the HostName or HostAddress property and the HTTPPort properties. In addition, when your system is connected to the Internet via a firewall system, you must also provide the ProxyServerAddress or the ProxyServerName before you can connect.

When the connection attempt succeeds, nResult is an integer that represents the socket number opened by the ConnectToHTTPServer method. The return of a socket number does not indicate successful connection; the HTTPServerConnection event fires when the connection attempts succeeds. When the connection attempt fails, nResult is 0 and the WSAError event fires.

See Also

HostAddress, HostName, HTTPPort, HTTPServerConnection, ProxyServerAddress, ProxyServerName, WSAError


GET Method

Applies To

CIHTTP

Purpose

The GET method retrieves the Web page from the location specified by the URL property.

Syntax

CIHTTP.GET

Data Type

None

Comments

Before invoking GET, you must be connected to a Web server (via the ConnectToHTTPServer method), and you must set the URL property.

GET updates the LocalFile, the HTMLPageTextWithTags, the AnchorListBox, the ImageFileListBox, the TagsListBox objects and the PacketReceived event.

See Also

AnchorListBoxName, HTMLPageTextWithTags, ImageFileListBoxName, LocalFileName, PacketReceived, TagListBoxName, URL


HEAD Method

Applies To

CIHTTP

Purpose

The HEAD method retrieves page information from the location specified by the URL property.

Syntax

CIHTTP.HEAD

Data Type

None

Comments

Set the URL property and before calling the HEAD method. HEAD updates the LocalFile object and the PacketReceived event.

See Also

LocalFileName, PacketReceived


POST Method

Applies To

CIHTTP

Purpose

The POST method lets you send parameters to a program on a Web server.

Syntax

CIHTTP.POST

Data Type

None

Comments

The POST method sends data as one or more parametername = parametervalue pairs.

Set the URL property before calling the POST method.

Example

See HTTP Form Parsing Project, "FormParse.vbp," for an example of a POST operation.

See Also

URL


SendHTTPCommand Method

Applies To

CIHTTP

Purpose

The SendHTTPCommand method lets you issue HTTP commands other than GET, HEAD, and POST.

Syntax

CIHTTP.SendHTTPCommand(Packet)

Data Type

String

Comments

Before invoking SendHTTPCommand, set the HostAddress or the HostName property, and the URL. In addition, if your system is connected to the Internet via a firewall system, you must also set the ProxyServerAddress or the ProxyServerName before invoking the SendHTTPCommand method.

The Packet is the HTTP command that you want to issue.

Note also that the when the SendHTTPCommand sends the packet, the PacketSent event fires.

See Also

GET, HEAD, HostAddress, HostName, PacketSent, POST, ProxyServerAddress, ProxyServerName, URL


General Tab

Applies To

CIHTTP

This custom tab lets you set these custom properties:

HostAddress Property	HostName Property	HTTPPort Property
LocalFileName Property	ParseIncomingData Property	URL Property


Sound Events Tab

Applies To

CIHTTP

This custom tab lets you assign sounds (via .WAV files) to custom events. The following lists the hidden properties that define the sound object and the event to which they are applied:

Event	Hidden Property
FileClosed Event	FileClosedWAV
HTTPServerConnection Event	HTTPServerConnectionWAV
HTTPServerConnectionClosed Event	HTTPServerConnectionClosedWAV
ListBoxesPopulated Event	ListBoxesPopulatedWAV
PacketReceived Event	PacketReceivedWAV
PacketSent Event	PacketSentWAV
SocketClosed Event	SocketClosedWAV
WSAError Event	WSAErrorWAV
You can set the sound associations at design time or run time. You can test the sounds from within the property page. At run time, an event is fired and a sound is played asynchronously where an association is made.

To associate a sound, you can type in the full qualified path for any events you want to associate or click the "Browse..." button and select it from the dialog box. After you enter a sound, you can click the test button to hear it. If the sound file is invalid or missing you will hear nothing when you


Related Topics

What Is HTTP?
What Is the CIHTTP Control?
Programming Tasks
Retrieve a Web Page
Posting Data to a Web Site
ciform.dll Description
How to use ciform.dll
HTMLForm Object
FormElement Object
OptVal Object

Back to the CIHTPP Reference


What Is HTTP?
Related Topics

The Hypertext Transfer Protocol lets you transfer data in HTML format. HTML is the HyperText Markup Language that is used in World Wide Web (WWW) documents. HTML lets you define HyperText links. A hypertext link is a type of formatting that lets you link a document to another document or lets you link items within a document. Hypertext links can be used to link documents from any WWW site in the world. They allow users to proceed from one Web site to the next. This process is sometimes called 'surfing'. The links are embedded in the Web documents. Web documents can contain text, images, and links. You use a browser to view an HTML page.


What Is the CIHTTP Control?
Related Topics

The Crescent Internet Hypertext Transfer Protocol control enables Visual Basic programmers to write customized World Wide Web (WWW) client applications. Client applications can retrieve text or binary data from a Web site, retrieve data about a page at the Web site or post text to a Web site from within an OLE container. The control can also be used to enhance the functionality of Web browsers.

CIHTTP has a simple programming interface in which you set property values and call methods to perform the desired tasks. When you call a method (which generally does not take arguments), the control takes the data it needs directly from the property sheet and submits it along with the request to the HTTP server. When the server returns a response, the control parses the data and updates, or refreshes, the properties as required so you can simply read the data from a property value or a ListBox object.


Programming Tasks
Related Topics

The CIHTTP control lets you build HTTP client applications. Each client application must contain code that connects to an HTTP server before it can issue any requests to the server. The connection requirements include:

1.	Setting the ParseURL property to True.

2.	Setting the URL property.

3.	Calling the ConnectToHTTPServer method.

The URL looks like this:

The code looks like this:

CIHTTP1.ParseURL = True
CIHTTP1.URL = http;//crescent.progress.com
nResult = CIHTTP.ConnectToHTTPServer

When the connection attempt succeeds, nResult is an integer that represents the socket number opened by the ConnectToHTTPServer method, and the HTTPServerConnection event fires. When the connection attempt fails, nResult is 0 and the WSAError event fires.

By nature, HTTP is transaction oriented, that is, you submit a request to an HTTP server, the server fulfills the request which completes the transaction. When a transaction completes, the server ends the connection. Thus, you can verify whether a transaction is complete by adding code to the FileClosed event module. You know that an error occurred when you get no data in response to a GET or HEAD method. When the POST method fails, the server returns an error code to the PacketReceived event.

Once connected, you can retrieve a Web page, or post data to a Web site.


Retrieve a Web Page
Related Topics

This section illustrates how you can use CIHTTP to retrieve a page from a Web site and store it to a file.

1.	Set these properties, then call the ConnectToHTTPServer.
ParseURL (set to True)
URL
LocalFileName
ParseIncomingData

When the connection is successful, the HTTPServerConnection event fires.

2.	After the HTTPServerConnection event fires, call the GET method to retrieve the Web page identified by the URL.

After the data is retrieved and parsed, the FileClosed event fires, and data from these properties can now be read:
The file identified by the LocalFileName property
The HTMLPageTextWithTags property
The HTMLPageTextWithoutTags property
The ListBox objects named by AnchorListBoxName,
ImageFileListBoxName,
and TagListBoxName properties
(if anchors, images, and tags exist in the Web page)
The PacketReceived event
The FileClosed event

The code looks like this:

Form_Load
CIHTTP1.ParseURL = True
CIHTTP1.URL = http;//crescent.progress.com
CIHTTP1.LocalFileName = C;\THEPAGE.HTM
CIHTTP1.ParseIncomingData = True
CIHTTP1.ConnectToHTTPServer

HTTPServerConnection_Event
CIHTTP1.GET


Posting Data to a Web Site
Related Topics

This section describes the Crescent Internet Form dynamic link library (ciform.dll), and how you can use it to parse Web forms and post data. The dll enables you to post data to a Web site quickly without having to look at the HTML source code to identify pertinent data fields and parameters. Also, ciform.dll automates query encoding.


ciform.dll Description
Related Topics

The ciform.dll consists of a tree structure of objects:  the HTMLForm object includes a collection of objects of the FormElement type, and the FormElement object includes a collection of objects of the OptVal type.  The following table describes the objects' properties.

Object	Property	Description
HTMLForm	Action	Read/write string.  After calling ParseForm, Action holds the URL to which the form will connect and send the form data.
	FormElements	Read/write collection - After calling ParseForm, FormElements holds a collection of objects of type FormElement.
	Method	Read/write string.  After calling ParseForm, Method will hold either GET or POST, defaulting to GET if no method was extracted from the form.  POST is the preferred method.
	Name	Read/write string.  After calling ParseForm, Name holds the name of the form (if any)
	Query	Read only string.  After calling ParseForm (and presumably modifying properties of the form elements), Query returns a single string containing the names and values of the elements in the form in the format name=value&name=value&name=value... Values are URL encoded to prevent illegal characters from appearing in the query.
	Setquery	Accepts CIHTTP control, returns Boolean.  Sets the URL and HTTPHeader properties of the CIHTTP control, and returns True if successful. If successful, you are ready to connect. However, in the connect event you still need to look at the Method property of the HTMLForm object to determine whether to GET or POST.
FormElement	Checked	Read/write boolean.  Determines if the item is checked. Only applies if ElementType is CHECKBOX.
	ElementType	Read/write string.  One of the following element types; CHECKBOX, HIDDEN, PASSWORD, RADIO, TEXT, TEXTAREA, and SELECT. The element type must allow data storage.  The BUTTON  element type, for example, is not valid since no value can be returned through a button.
	MaxLength	Read/write string.  The maximum number of characters the server will allow. Only applies if ElementType is TEXT, PASSWORD, or TEXTAREA.  A value of zero means there is no limit.  Refer to this property before setting the Value property of a TEXT, PASSWORD, or TEXTAREA to make sure you do not exceed the server's limit.
	Multiple	Read/write boolean.  Determines whether multiple selections are allowed. Only applies if ElementType is SELECT.
	Name	Read/write string.  The name of the element.
	Options	Read/write collection.  A collection of objects of type OptVal. Only applies if ElementType is SELECT or RADIO.
	Value	Read/write string.  The value of this element. Only applies if ElementType is HIDDEN, PASSWORD, TEXT, or TEXTAREA.
OptVal	Selected	Read/write boolean.  Determines if the option is selected.
	Value	Read/write string. The value of this element.


How To Use ciform.dll
Related Topics

Follow these steps to use ciform.dll:

1.	Include the reference Crescent HTML Form Object in your project.

2.	Create an HTML Form object; enter Dim MyForm As HTMLForm in the general section. This object must be a module-level variable to enable you to check the object's Method property inside CIHTTP's HTTPServerConnection event.

3.	Set MyForm = New HTMLForm  to clear the object of any previous values.

4.	Call the FindHTMLForm method, and pass to it a string of HTML data containing at least one form. If the method finds the form, it returns a TRUE response.

5.	This step is optional. If you want to be sure the method has found the form you were expecting (although the Name property might be set, most forms are unnamed), examine the FormElements collection to be sure the elements you need are there. See Step 5 Example at the end of this procedure.

To find subsequent forms in the page, call the FindHTMLForm method without arguments.

When no more forms are found, or when a form parsing error occurs, the method returns a FALSE response.

6.	Edit the properties of each item in the FormElements collection. See Step 6 Example at the end of this procedure.

7.	Call the SetQuery method and pass it a CIHTTP control. This method sets the URL and HTTPHeader properties of the CIHTTP control. Be sure the CIHTTP control's ParseURL property is set to True before calling this method.

8.	Connect to the server with CIHTTP. In the HTTPServerConnection event, you must look at the Method property of the HTMLForm object to determine whether to call the GET or POST method.

NOTE  	If you do not find a form on the HTML page you expected to find it, it is probably because the page uses frames. In this case, the HTML code contains one or more FRAME SRC entries, with the name of another document following each entry. One of these documents contains the form you expected to find.

Step 5 Example

' Find an element called address, if not found
' the Web page has changed and we cannot
' programmatically process the form.

Dim frm As Object
Dim foundAddr As Boolean

foundAddr = False

For Each frm In MyForm.FormElements
If frm.Name = address Then
foundAddr = True
Exit For

End If
Next

If foundAddr = False Then
MsgBox Form has changed, cannot process
' Other cleanup code here
End If

Step 6 example

<FORM NAME=form1 ACTION=http;//somehost.com/cgi-bin/myprog.exe
 METHOD=POST>
<INPUT TYPE=TEXT NAME=text1>
<CHECKBOX NAME=check1 CHECKED>
<SELECT NAME=select1 MULTIPLE>
<OPTION VALUE=opt1>This text ignored because value was set
<OPTION>This text becomes the value by default
<OPTION VALUE=opt3 SELECTED>This option is the default selection
</SELECT>
</FORM>

--------

And the code:

--------
Dim f as New HTMLForm
Dim MyQuery As String

' Assume page has just been downloaded by CIHTTP1, and this page
' contains' the form above. CIHTTP1.ParseIncomingData = True, 'CIHTTP1.ParseURL = True

If f.FindHTMLForm(CIHTTP1.HTMLPageTextWithTags) Then
' Assume TEXT
f.FormElements.Item(1).Value = some text '

' Assume CHECKBOX
f.FormElements.Item(2).Checked = True

' Assume SELECT
f.FormElements.Item(3).Options.Item(1).Selected = True

' Sets the URL and HTTPHeader properties. Assumes that the form ca	' came from the document just downloaded by CIHTTP, so that the 	' form's Action property (which is probably a relative URL)
' can be expanded.

If f.SetQuery(CIHTTP1) Then
' All ready to go. Inside the connect event, check f.Method to
' determine whether to GET or POST.
CIHTTP1.ConnectToHTTPServer
End If
Else
' ParseForm failed
End If


HTMLForm Object
Related Topics

The browser (or your program) is the only user of the Name property; the program uses the property to identify the form. The Name property is not sent back to the server with the rest of the query.

The Action property is the URL of the program on the server that processes the query. By changing this property, you can redirect the query to another location. This might help you to test your application.

You should examine the Method property inside the HTTPServerConnection event of a CIHTTP control to determine whether to GET or POST.

The FormElements object is a collection of FormElement objects, which are described below.


FormElement Object
Related Topics

The Name property in the query identifies a parameter. For example, if it is a text box called name containing Bill, the query includes name=Bill. Do not change the name property.

The ElementType property determines how to set the value of this element. Below are the supported types and how to use them.

NOTE  	The types are case sensitive in the HTML code of a page.  By default, the dll converts the type to uppercase.  We recommend that you use uppercase types in your Visual Basic code to avoid having to watch the use of case constantly.

TEXT, TEXTAREA, and PASSWORD

These text types are set with the Value property. If the Maxlength property is other than zero, the Value string is limited in length.

HIDDEN

Normally, you should not change this type from its default value. However, if you do change it, change it with the Value property. This type embeds hidden values in an HTML form in order to package them into the query.

CHECKBOX

Set this type with the Checked property.

RADIO and SELECT

Both these types use the Options property to hold a collection of OptVal objects. If the element is a Select, the Multiple property may be True. If the Multiple property is True, you can select multiple Options.


OptVal Object
Related Topics

The Value property contains the value of this particular item in a Select or Radio type. To select it, set the Selected property to True.